package vfs.obj.association;

import vfs.obj.entity.VFSUser;
import vfs.obj.entity.VFSGroup;
import vfs.filter.VFSFilter;
import java.util.Iterator;

/**
 * VFSUserToGroup is an association manipulator capable of 
 * manipulating the "belongs to" relationship between Users and Groups.
 * 
 * @author Matthew Eavenson <durandal@uga.edu>
 */
public interface VFSUserToGroup{
    
    /**
     * Returns an iterator over all users in a specified group,
     * and filtered by a specified filter.
     * 
     * @param group the group of which the requested users are members
     * @param filter a filter over the users in the specified group
     * @return an iterator over any matching users
     */
    Iterator<VFSUser> getUsers(VFSGroup group, VFSFilter filter);
    
    /**
     * Returns an iterator over all groups that a specified user is a member of,
     * and filtered by a specified filter.
     * 
     * @param user the user that is a member of the requested groups
     * @param filter a filter over the groups of the specified user
     * @return an iterator over any matching groups
     */
    Iterator<VFSGroup> getGroups(VFSUser user, VFSFilter filter);
    
    /**
     * Adds a specified user to a specified group.
     * 
     * @param user the user to be added to the specified group
     * @param group the group for which to assign the specified user as a member
     */
    void addUserToGroup(VFSUser user, VFSGroup group);
    
    /**
     * Removes a specified user from a specified group.
     * 
     * @param user the user to be removed from the specified group
     * @param group the group for which to remove the specified user as a member
     */
    void removeUserFromGroup(VFSUser user, VFSGroup group);
    
}
